<HTML><HEAD><TITLE>cursor_next_execute(++Cursor, +Tuple)</TITLE>
</HEAD><BODY>[ <A HREF="index.html">library(dbi)</A> | <A HREF="../../index.html">Reference Manual</A> | <A HREF="../../fullindex.html">Alphabetic Index</A> ]
<H1>cursor_next_execute(++Cursor, +Tuple)</H1>
Executes the parametrised prepared SQL statement represented by Cursor.
<DL>
<DT><EM>Cursor</EM></DT>
<DD>A cursor handle
</DD>
<DT><EM>Tuple</EM></DT>
<DD>A tuple of parameter values matching the template for this cursor (structure)
</DD>
</DL>
<H2>Description</H2>
<P>
 Executes the parameterised prepared SQL statement represented by Cursor,
 previously prepared by session_sql_prepare/4 or session_sql_prepare_query/5.
 The parameter values for this execution is supplied by Tuple.
</P><P>
 Tuple is a structure whose name and arity match the parameter template
 when Cursor was prepared, and the arguments give the values for the
 parameters for this execution, and must be compatible with the type
 specified by the template, except that an argument can be an
 uninstantiated variable, to denote a NULL value for the corresponding
 parameter.
</P><P>
 If the SQL statement is a query, and was prepared as a query using
 session_sql_prepare_query/5, results can be obtained from the query by
 the cursor_*_tuple family of predicates.
</P><P>
 This predicate is called with default options for the cursor, i.e. it is
 equivalent to calling cursor_next_execute/3 with an empty Options list.
 

<H3>Exceptions</H3>
<DL>
<DT><EM>(5) type error </EM>
<DD>Cursor is not a valid cursor handle
<DT><EM>(5) type error </EM>
<DD>Type mismatch between parameter template specification for Cursor and actual tuple data
<DT><EM>(dbi_buffer_over) </EM>
<DD>Parameter value(s) too big for the buffer
<DT><EM>(dbi_error) </EM>
<DD>Error from DBMS while executing SQL associated with Cursor.
<DT><EM>(dbi_bad_template) </EM>
<DD>ParamTemplate not specified when Cursor was created
<DT><EM>(dbi_bad_cursor) </EM>
<DD>The Cursor is not in a state to execute a query (e.g. it was cancelled)
</DL>
<H2>Examples</H2>
<PRE>
  % note '?' in SQL in the syntax MySQL uses for placeholders. This may be
  % different in other DBMS
  transfer_(Session, Amount, FromAccount, ToAccount) :-
      SQL = "update accounts set balance = balance + ? \
                                               where id = ?",
      Deduct is - Amount,
      % incbal(1.0,12) is the parameter template
      session_sql_prepare(Session,incbal(1.0,12),SQL,Update),
      cursor_next_execute(Update,incbal(Deduct,FromAccount)),
      cursor_next_execute(Update,incbal(Amount,ToAccount)).</PRE>
<H2>See Also</H2>
<A HREF="../../lib/dbi/cursor_next_execute-3.html">cursor_next_execute / 3</A>, <A HREF="../../lib/dbi/cursor_all_execute-2.html">cursor_all_execute / 2</A>, <A HREF="../../lib/dbi/cursor_N_execute-4.html">cursor_N_execute / 4</A>, <A HREF="../../lib/dbi/session_sql_prepare-4.html">session_sql_prepare / 4</A>, <A HREF="../../lib/dbi/session_sql_prepare_query-5.html">session_sql_prepare_query / 5</A>
</BODY></HTML>
